Skip to content

export: mdl export erwin — XSD-valid erwin XML that round-trips via the importer - #60

Merged
dbose merged 2 commits into
mainfrom
feat-erwin-export
Nov 1, 2026
Merged

dbose merged 2 commits into
mainfrom
feat-erwin-export

Conversation

@dbose

@dbose dbose commented Nov 1, 2026 •

Copy link
Copy Markdown
Owner

What

The inverse of mdl import erwin: export a Modelith model to erwin XML. Teams that live in erwin Data Modeler can push a Modelith-authored or reverse-engineered model back out.

Guarantees (both verified end to end)

  • XSD-valid against erwin/ERwinSchema.xsd — root <erwin FileVersion="9.8.0000" Format="erwin"> → namespaced <Model id> with the required ModelEnvProps/ModelProps, every object with an id and its *Props child. (9.8.00 is INVALID — the pattern needs 4 build digits.)
  • Round-trips through our own importer back to an equivalent model: entities, attributes (domain/role/nullable), key-group members in order, relationships (ends + cardinality + verb phrases), categories (+ discriminator), subject-area membership, and domains.

How

emit_erwin(model, *, naming) -> str in packages/emit-erd mirrors the importer's reads in reverse, undoing its asymmetries:

  • folds the conceptual+logical split back into one <Entity> (Name = display, Physical_Name = raw snake);
  • re-emits each Category as subtype <Relationship Type="Subtype_*"> with a discriminator;
  • from = child/many side, to = parent/one side; PK key-group membership drives role.
  • Mints stable erwin GUIDs from ULIDs so output is reproducible (golden-friendly).

Opt-in team naming via export.erwin.naming in mdl-project.yaml (ErwinNaming/ExportConfig in ir.py), off by default = verbatim. Rewrites LOGICAL/display names only (underscore→space, title/upper/lower); Physical_Name always stays the raw identifier. (erwin does not enforce naming at the XSD level — confirmed — so it's the exporter's job.)

CLI: mdl export erwin -m <model> -o <file>, mirroring export dbml.

Tests

12 new (10 emitter + 2 CLI): XSD validity, FileVersion/skeleton guard, round-trip equivalence, key-group member order, category+discriminator, verb phrases, subject-area membership, naming convention (logical-only, physical untouched), reproducibility, CLI write + config path. Full suite 1025 passed; ruff clean.

Scope / notes

  • Real erwin Data Modeler open-ability is out of scope (unverifiable without erwin); the target is the published XSD + our importer. The command help says so.
  • The strict XSD encodes key-group membership opaquely (Built_In_Id) but tolerates the importer-readable <Attribute_Ref> form, so we emit that and satisfy both goals.
  • Subject-area membership round-trips for entity members; erwin (and our importer) don't carry glossary-term members of a subject area — an inherited importer limitation, not an export bug.
  • erwin/*.xsd is gitignored (reference/validation only); the XSD-validity test skips gracefully when the XSDs or xmllint are absent, so CI without them still runs the round-trip tests.

dbose added 2 commits November 1, 2026 08:18
…he importer

The inverse of 'mdl import erwin'. Teams that live in erwin Data Modeler can push a
Modelith-authored or reverse-engineered model back out as erwin XML.

- emit_erwin(model, *, naming) in packages/emit-erd (pure Model->str), mirroring the
  importer's reads in reverse. Undoes the importer's asymmetries: folds the
  conceptual+logical split back into one <Entity> (Name=display, Physical_Name=raw); re-emits
  each Category as subtype <Relationship Type=Subtype_*> with a discriminator; from=child/many,
  to=parent/one; PK key-group membership drives role. Mints stable erwin GUIDs from ULIDs so
  output is reproducible.
- Validates against the real erwin XSD: root <erwin FileVersion=9.8.0000 Format=erwin> ->
  namespaced <Model id> with required ModelEnvProps/ModelProps. (9.8.00 is INVALID — the
  pattern needs 4 build digits.)
- Opt-in team naming convention via export.erwin.naming in mdl-project.yaml (ErwinNaming/
  ExportConfig in ir.py), off by default = verbatim. Rewrites LOGICAL/display names only;
  Physical_Name always stays the raw snake identifier.
- CLI: 'mdl export erwin -m <model> -o <file>', mirroring export dbml.

Verified end to end: import sample.erwin.xml -> export -> xmllint --schema validates ->
re-import -> mdl validate passes, counts/keygroups/category/verb-phrases equivalent. 11 new
tests (XSD validity, round-trip equivalence, key-group member order, category+discriminator,
verb phrases, naming convention, reproducibility). Full suite 1025 passed.

Note: real erwin Data Modeler open-ability is out of scope (unverifiable without erwin); the
target is the published XSD + our importer. The strict XSD models key-group membership opaquely
(Built_In_Id); we emit the importer-readable Attribute_Ref form, which the XSD still accepts.
The round-trip test only checked subject-area names/counts, not that each area keeps its
member entities. Membership is stored as conceptual-entity ids and travels through export as a
Ref_Array, so it's the part most likely to silently drop. Add a test resolving each area's
members back to entity names and asserting equality across export->reimport. Verified: the
sample's 'Trading' area keeps [counterparty, trade].
@dbose
dbose merged commit bbc4636 into main Nov 1, 2026
2 checks passed
dbose added a commit that referenced this pull request Nov 1, 2026
0.7.2 -> 0.8.0 (minor). Ships 'mdl export erwin': XSD-valid erwin XML that round-trips via
the importer (PR #60), plus the opt-in export.erwin.naming model-config block. New user-facing
command + config surface, so a minor bump per the versioning rule.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant